3D Images/3D Images.iso/programs/amiga/biganim/biganim.doc

Text File | 1995-01-12 | 10KB | 272 lines

            *--------------*
            | BigAnim v4.0 |
            *==============*


    What is BigAnim?
    ~~~~~~~~~~~~~~~~
BigAnim is an animation player (you guessed it!), and it's called that
because it is able to display animations that are too large to be loaded
into memory directly.

The most important features of BigAnim are:

o BigAnim loads the animation asynchronously, 100 KByte at a time, which
  means that while it displays one 100 KByte part of the animation, it is
  loading the next 100 KByte simultaneously.

o If you're using Kickstart 3.0 or later, BigAnim will use the new double-
  buffering routines in graphics.library. If you're not, BigAnim will take
  over the display from Intuition, to increase playback speed. However, if
  you flip screens, or pull down BigAnim's screen, BigAnim will detect
  this, and use the old, intuition-friendly (and slow!) routines instead.

o BigAnim has sound support.


    Usage
    ~~~~~
From a CLI or shell, the usage is:

    BigAnim filename [LOADALL] [HIRES] [BLANK] [VERBOSE]
                     [BUFSIZE n] [RELTIME n] [TASKPRI n]

where "filename" should refer to an ANIM type 5 or 7 animation. ANIM
type 8 is not supported, due to its relative inefficiency compared to
ANIM type 7. For best results, type 8 animations should be converted to
type 7. BigAnim can also be used from Workbench, and the tool types
are identical to the options.


    Options
    ~~~~~~~
    LOADALL

Tells BigAnim to load the whole animation before starting playback.
Note that the animation is loaded in chunks, and the size of these
chunks can be set with the BUFSIZE keyword.

    HIRES

Forces the screen resolution to Hires/Interlace. This will only work
if the original resolution was lores/nolace.

    BLANK

Blanks the mouse pointer.

    VERBOSE

BigAnim prints some info about the animation, such as screen size/depth,
display modes, animation type, etc.

Example:                Explanation:

File:     Juggler            File name
Picture:  320 x 200 (48000 bytes)   Picture size (width, height & bytes)
Display:  320 x 200 x 6 planes        Display resolution & depth
Modes:    PAL:Low Res Ham        View modes
AnimType: 5                Anim type: 5, 7 (short) or 7 (long)
Length:   24 frames            The number of frames in the anim
Speed:    50 fps            Actual playback speed (frames/second)
BufUsage: 92-98 %            Buffer utilization percentage (min-max)

Note: The actual numbers for the last four lines won't be printed until
the animation has been displayed once (twice for the "Speed" and "BufUsage"
numbers), simply because that information isn't available until then.
The "BufUsage" numbers will not be printed if you're using the LOADALL
switch.

    BUFSIZE n

Sets the buffer size to n bytes. The default is 102400 bytes (100 K), which
means that BigAnim loads 100 K at a time.

    RELTIME n

Sets the playback timing, in 1/50 seconds if you're running on a PAL
system, or 1/60 for NTSC systems.

    TASKPRI n

This sets BigAnim's task priority during playback. If your hard disk
controller doesn't use DMA, the playback will probably be less jerky if
you use a high task priority. The best value for priority is generally
the same as the file system or the hard disk driver uses. Actually,
TASKPRI can be used with good results even on DMA controllers: On my
setup with an A590 and a Quantum LP240S, the playback becomes somewhat
smoother when I use TASKPRI 11.


    Keys
    ~~~~
While the animation is being played, you can press the following keys:

ESC       - Quits BigAnim (you can also use the right mouse button)
Space     - Pauses the animation, or restarts if already paused
N         - If paused, displays the next frame
0-9       - Changes playback speed. By pressing one of the keys 1-9 or
F1-F10      F1-F9 you can directly set the RELTIME value during playback.
            If you press 0 or F10, BigAnim will use the timing information
            stored in the animation.


    Environment
    ~~~~~~~~~~~
If you want to use certain options or settings as default, you can save
them in an environment variable called BIGANIMOPTS. So, for instance, if
you always want to use a buffer size of 204800 bytes, do:

    SetEnv BIGANIMOPTS BUFSIZE 204800

and BigAnim will use that instead of the built-in default of 102400 bytes.
Values for BUFSIZE, RELTIME and TASKPRI set via BIGANIMOPTS can be over-
ridden with the respective command line options. All options except LOADALL
can be used in BIGANIMOPTS.


    Sound support
    ~~~~~~~~~~~~~
BigAnim has the ability to play IFF 8SVX sounds synchronized with the
animation. These sounds may be added to an animation in two steps:

1) The sounds must be placed at the beginning of the animation file,
immediately before the first ILBM picture in the animation. The file will
have the following structure:

FORM ANIM
   FORM 8SVX
   FORM 8SVX
   :
   :
   FORM ILBM
   FORM ILBM
   :
   etc.

2) If a sound is to be started at a certain frame, this frame should contain
an "SCTL" chunk. It looks like this:

struct SoundControl {
   UBYTE  sc_Command,    // What to do, see below
          sc_Volume;    // Volume 0..64
   USHORT sc_Sound,    // Sound number
          sc_Repeats,    // Number of times to play the sound
          sc_Channel,    // Channel(s) to use for playing (bit mask)
          sc_Frequency,    // If non-zero, overrides the VHDR value
          sc_Flags;    // Flags, see below
   UBYTE  pad[4];    // For future use
};

The sound number, starting at 1, is simply determined from the order of
the sounds in the file. The "Repeats" field may be set to 0, which means
that the sound will be repeated continuously.

Currently, BigAnim supports these sound commands:

#define SC_CMD_PLAY_SOUND  1    // Start playing a sound
#define SC_CMD_STOP_SOUND  2    // Stop the sound in a given channel
#define SC_CMD_SET_FREQVOL 3    // Change frequency/volume for a channel

Sound flags:

#define SCB_NOINTERRUPT 0    // Play the sound, but only if
#define SCF_NOINTERRUPT (1<<0)    // the channel isn't in use

Sometime soon (TM), I will release a new version of my animation tool
"BuildAnim", that will be able to build animations with sounds, and add
sounds to existing animations.


    Additional info
    ~~~~~~~~~~~~~~~
o BigAnim supports CMAP chunks internal to the animation, and changes the
  screen colors accordingly.

o BigAnim uses the RelTime field of the ANHD chunk to decide how much
  delay to put between frames. You can override this value by specifying
  a new value with the RELTIME keyword, or by pressing a number key during
  playback.

o BigAnim uses two sets of specially optimised decompression routines,
  for processors with and without instruction cache.


    How to choose the best buffer size
    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
To maximize playback speed, do this: If you have enough memory in your
Amiga to load the entire animation, use the LOADALL switch. This will
lead to the fastest possible playback. If you don't have that much
memory, you can try different buffer sizes with the BUFSIZE keyword.
Tip: If you use the VERBOSE option, BigAnim will measure the playback
speed, so you can easily see how different buffer sizes affect playback.
Also, the "BufUsage" numbers will tell you how well the buffers are
utilized during playback.

When choosing buffer size, please keep these facts in mind:

1. Due to the asynchronous nature of BigAnim's loading method, using
the largest possible buffer size may not give the fastest playback.

2. Certain combinations of file size and buffer size should be avoided.
An example: If you use a buffer size of 300 KBytes with an animation
that's 1000 KBytes long, then the first three reads will read 300 KBytes
each, but the fourth will only read 100 KBytes. This is clearly not
optimal. It would be much better to use a buffer size of 250 or 334
KBytes (or just a little bit more, to be on the safe side). So, in
cases when the last read of an animation is less than half as long as
the others, BigAnim will print a warning message: "non-optimal buffer
size".

There are two common problems often encountered while trying to find the
ideal settings:

Common problem #1: Sometimes the playback stops for a while, then continues.

Reason: Either (1) your hard disk cannot read fast enough to keep up with
the playback, (2) your hard disk doesn't have enough buffers, or (3) the hard
disk driver uses all available CPU time so the playback stops.

Solution: (1) Increase buffer size, and/or use RELTIME to slow down play-
back so the hard disk can keep up. (2) Use "AddBuffers" to add more buffers
to your hard disk. BigAnim uses the DOS "Seek" function from time to time,
and the "Seek" operation will be much faster if you have enough buffers.
"Enough" is approximately one buffer for every 36 KBytes of data in the
animation file. (3) Use TASKPRI to increase BigAnim's task priority. Usually,
using the same priority that the hard disk driver uses will give the best
results.

Common problem #2: Now and then the playback slows down temporarily.

Reason: Due to hard disk transfer, the decompression can't be done at full
speed.

Solution: Use RELTIME to slow down the playback. The playback will of course
be slower, but not as jerky as before.


    Disclaimer
    ~~~~~~~~~~
#include <std/disclaimer.h>


    Distribution
    ~~~~~~~~~~~~
BigAnim is freely distributable, as long as BigAnim and all related files
are distributed unchanged.


    Feedback
    ~~~~~~~~
If you want to send me suggestions, bug reports, etc, I can
be reached at:

Internet:    [e-mail]

Snail-mail:    Christer Sundin
        7321 Bollestad
        S-442 93 Kungälv
        Sweden